Job selectors

Many of the methods in JPPFClient and in the job management interface DriverJobManagementMBean use a JobSelector, which allows filtering the jobs in the client's or driver's queue according to user-defined criteria. This interface is defined as folows:

public interface JobSelector extends Serializable {
  // Whether the specified job is accepted by this selector
  boolean accepts(JPPFDistributedJob job);

  // Negate this job selector
  default JobSelector negate()

  // Obtain a job selector that realizes a logical "and" operation on this selector and an other
  default JobSelector and(final JobSelector other) throws NullPointerException

  // Obtain a job selector that realizes a logical "or" operation on this selector and an other
  default JobSelector or(final JobSelector other) throws NullPointerException

  // Obtain a job selector that realizes a logical "xor" operation on this selector and an other
  default JobSelector xor(final JobSelector other) throws NullPointerException
}

As we can see, it acts as a yes/no filter for instances of JPPFDistributedJob, which represent client-side or server-side jobs. Job selectors are similar in functionality to the node selectors seen later in this documentation. Job selectors can also be composed into complex predicates, by the means of the logical operators "and", "or", "xor" and "negate".

The JPPF API provides a number of predefined implementations of JobSelector, which perform comparisons or tests on the data provided by the JPPFDistributedJob interface: job uuid, name, SLA and metadata. Many of these selectors can work with or without a metadata key. When a metadata key is not specified, the selector will apply to the jobs' names.

1 Logical job selectors

As mentioned previously, job selectors can be composed into more complex predicates, using the boolean operators "and", "or", "xor" and "negate". they can be used as follows:

// matches jobs whose value for metadata key "key1" is "value1"
JobSelector selector1 = new EqualJobSelector("key1", "value1");
// selects jobs whose name matches the regex .*my_job.*
JobSelector selector2 = new RegexJobSelector(".*my_job.*");

// compose the selectors using logical operators
JobSelector andSelector  = selector1.and(selector2);
JobSelector orSelector   = selector1.or(selector2);
JobSelector xorSelector  = selector1.xor(selector2);
JobSelector notSelector2 = selector2.negate();

2 AllJobsSelector

An instance of AllJobsSelector will select all the jobs present in the driver at the time a management request is made. To use it, you can either construct a new instance or use the predefined constant JobSelector.ALL_JOBS. For example:

DriverJobManagementMBean jobManager = ...;
// get information on all the jobs
JobInformation[] jobInfos = jobManager.jobInformation(new AllJobsSelector());
// alternatively, use the ALL_JOBS constant
jobInfos = jobManager.jobInformation(JobSelector.ALL_JOBS);

3 Job uuid and name selectors

Instances of JobUuidSelector and JobNameSelector filter jobs based on a set of job uuids or job names, provided in one of their constructors. Example usage:

// create a selector with known uuids
JobSelector uuidSselector = new JobUuidSelector("job_uuid_1", "job_uuid_2");
// create a job name selector from alist of names
List<String> names = new ArrayList<>();
for (JPPFjob job: jobs) names.add(job.getName());
JobSelector nameSelector = new JobNameSelector(names);

4 Binary comparison selectors

The selectors AtLeastJobSelector, AtMostJobSelector, EqualsJobSelector, LessThanJobSelector, MoreThanJobSelector and NotEqualsJobSelector respectively perform the equivalent of the mathematical comparisons >=, <=, =, <, > and !=. However, they apply to any Comparable value, so they are not limited to numbers.

These selectors can be applied to either a job metadata value, if a key is specified, or to a job name otherwise.

Here are some examples:

JobSelector selector;
// value of metadata "my.counter" should be >= 5
selector = new AtLeastJobSelector("my.counter", 5);
// "my.date" metadata should be no later than 5 minutes from now
selector = new AtMostJobSelector("my.date", ZonedDateTime.now().plusMinutes(5));
// job name should be equal to "first job"
selector = new EqualsJobSelector("first job");
// enums are comparable too
selector = new LessThanJobSelector("jobType", MyJobType.PROD);
// the "ratio" metadata should be more than the double value 0.65
selector = new MoreThanJobSelector("ratio", 0.65d);
// "my.file" must not point to "/opt/app/config.yml"
selector = new NotEqualsJobSelector("my.file", new File("/opt/app/config.yml"));

5 Range comparison operators

The selectors BetweenEEJobSelector, BetweenEIJobSelector, BetweenIEJobSelector and BetweenIIJobSelector respectively perform the equivalent of the range comparisons a < x < b, a < x <= b, a <= x < b and a <= x <= b. Similarly to binary comparisons, they work with any Comparable value and may apply to a job name, or a metadata value if its key is specified.

Examples:

JobSelector selector;
// "amount" must be more than 100.0 and less than 500.0
selector = new BetweenEEJobSelector("amount", 100d, 500d);
// "date" must be after 2 hours ago and no later than 45 minutes from now
ZonedDateTime now = ZonedDateTime.now();
selector = new BetweenEIJobSelector("date", now.minusHours(2), now.plusMinutes(45));
// job name must be at least "job1" and less than "job2". Example: "job12-hello"
selector = new BetweenIEJobSelector("job1", "job2");
// "day.of.week" must be from monday to wednesday included
selector = new BetweenIIJobSelector("day.of.week", DayOfWeek.MONDAY, DayOfWeek.WEDNESDAY);

6 Contains, one of and regex job selectors

These selectors perform the following boolean functions:

• ContainsJobSelector: determines whether a job name or metadata value contains a substring. If the value of the specified metadata is not a stinrg, the result is false.
• IsOneOfJobSelector: determines whether is one of a collection or array of values, based on equals() comparisons.
• RegexJobSelector: applies a regex to a job name or metadata value and returns whether it matches or not. It only applies to string values. If the value of the specified metadata is not a string, false is returned.

Some usage examples:

JobSelector selector;
// the metadata "label" must have a substring "test string"
selector = new ContainsJobSelector("label", "test string");
// the metadata "dayOfMonth" must be either 1, 7, 14 or 28
selector = new IsOneOfJobSelector("dayOfMonth", 1, 7, 14, 28);
// the job name must have a substring "test" (case insensitive) followed by at least one digit
selector = new RegexJobSelector(".*test[0-9]+.*", Pattern.CASE_INSENSITIVE);

7 Scripted job selector

A ScriptedJobSelector uses a script expression that evaluates to a boolean to determine which jobs are accepted. The script language must be accepted by the JVM and must conform to the JSR-223 / javax.script API specifications.

A scripted job selector is particularly useful when you need to implement a complex filtering logic but do not want to deploy the associated code in the driver's classpath.

ScriptedJobSelector extends BaseScriptEvaluator and is defined as follows:

public class ScriptedJobSelector extends BaseScriptEvaluator implements JobSelector {
  // Initialize this selector with the specfied language and script
  public ScriptedJobSelector(String language, String script)

  // Initialize this selector with the specfied language and script reader
  public ScriptedJobSelector(String language, Reader scriptReader) throws IOException

  // Initialize this selector with the specfied language and script file
  public ScriptedJobSelector(String language, File scriptFile) throws IOException

  @Override
  public boolean accepts(final JPPFDistributedJob job)
}

The script will be evaluated for each JPPFDistributedJob passed as input to the accepts() method of the selector. The job can be accessed from the script using a predefined variable named "jppfJob", as in this example:

DriverJobManagementMBean jobManager = ...;
// create a selector with a Javascript script
String script = "jppfJob.getName().startsWith('MyJob-')";
JobSelector selector = new ScriptedJobSelector("javascript", script);
// or an equivalent Groovy script
selector = new ScriptedJobSelector("groovy", "return " + script);
// get information on the selected jobs
JobInformation[] jobInfos = jobManager.jobInformation(selector);

8 Custom job selector

When a job selector requires a complex logic and its performance is critical, you can always write your own implementation of JobSelector, as in this example:

public class CustomJobSelector implements JobSelector {
  @Override
  public boolean accepts(JPPFDistributedJob job) {
    // retrieve a parameter from the job metadata
    int param = job.getMetadata().getParameter("my.param", -1);
    // use the param in the filtering expression
    return !job.getSLA().isSuspended() && (param >= 0);
  }
}

When the job selector is evaluated by the driver, the code of its implementation, along with all the classes it depends on, must be deployed in the driver's classpath. This is usually done by dropping the class folder or jar file that contains the code in the driver's /lib folder.